Collection of Tools & Utilities/Collection of Tools and Utilities.iso/batchut/batmn21e.zip/BATMAN.DOC

Text File | 1990-12-01 | 24.4 KB | 837 lines

    │
    │ B A T M A N   2 . 1 e
    │
    │ - a batch file
    │   compiler
    │
    │ Thor Ivar Ekle 1989, 90
    │




    WHAT IS BATMAN?
    ───────────────

    Batman is a utility for compiling batch files, or, in other words,
    translating .BAT-files into .EXE-files. There are two reasons why you
    might to bother with this; first, .EXE-files usually execute much
    faster than .BAT-files. Secondly, batch files are normal text files,
    which means that they can be printed on a screen or printer, whereas
    .EXE-files are unreadable to anyone but a PC. Besides, Batman adds a
    lot of functionality which the DOS batch language lacks.

    This version of Batman is free. You may make as many copies as you
    like, and please feel free to give away copies of the program. You may
    not, however, sell part or whole of this package. All distribution of
    Batman is to done by means of the file BATMN21E.ZIP, which shall
    contain these files:

        BATMAN.EXE   - the compiler.
        ROBIN.DAT    - data file used by Batman.
        BATMAN.DOC   - this file.
        BATNEWS.TXT  - summary of the latest news in Batman.
        TRACY.EXE    - interactive debugger.
        TRACY.DOC    - documentation for Tracy.
        COLORS.EXE   - utility which displays the available color codes.
        EXCOM.EXE    - utility which reports how external commands are
                       executed.
        GCD.EXE      - utility which displays the directory tree and lets
                       you change the current directory.
        MEXEC.EXE    - utility which lets you select files and pass them as
                       arguments to a specified command.

    Should you have any questions regarding Batman, please feel free to
    call me at [phone].



    USING BATMAN
    ────────────

    The command for starting Batman is:

        BATMAN [/A] [/C] [/D] <batch file>

    The parameter <batch file> is the name of the .BAT-file you wish to
    compile.

    Options:

        /A:  If there already exists a file by the same name as the
             batch file with the extension .EXE, Batman will normally ask
             you to confirm that it should be replaced before compilation
             starts. Also, the message "Done - press <─┘" is displayed
             after Batman has completed a successful compilation. These two
             messages are omitted if this option is selected. This is
             useful for automatic compilations.

        /C:  This option forces Batman to always use COMMAND.COM for
             execution of external commands. See the section "External
             Commands" for more information.

        /D:  Use this option if you wish to debug the program file with
             the interactive debugger Tracy. See the documentation for
             Tracy for more information.

    You may include a full path in <batch file> if the desired file isn't
    located in the current directory. You may omit the extension ".BAT",
    but other extensions are not accepted. Batman will search for the
    requested file, and display an error message if it can't be found.

    If found, a new file with the same name, but with the extension ".EXE"
    will be created. If such a file already exists, you will be asked to
    confirm that it should be overwritten and replaced by the new file. The
    resulting .EXE-file will be stored in the same directory as the
    batch file.

    During compilation, the file ROBIN.DAT must be available. This file is
    not required by the compiled program file.

    The batch file may contain most DOS commands, plus, of course, Batman's
    internal commands. The internal commands are:


    BELL
    ────

    Produces a beep. Useful for alerting the user when a time-consuming
    task has completed.


    CALL
    ────

    This command is used to execute other compiled batch files. The format
    is:

        CALL <filename>

    When you compile a batch file which contains CALL-commands, Batman will
    display a list of the referenced batch files after compilation has
    completed. This is to remind you to compile these files as well before
    trying to run the program file.

    The procedure for calling uncompiled batch files is described in a
    later section.


    CLOCK
    ─────

    Displays a clock on the screen. Formats:

        CLOCK ON <column> <line> <foreground color> <background color>
        CLOCK OFF

    The form CLOCK ON displays the current time on the screen in the
    desired location and in the chosen colors. CLOCK OFF stops the clock,
    but does not remove the last displayed time.


    CLREOL
    ──────

    Blanks the current line, starting with the cursor position.


    CLS
    ───

    Blanks the whole screen.


    COLOR
    ─────

    Select the colors in which text is displayed on the screen. Parameters
    are foreground and background colors. The format is:

        COLOR <foreground color> <background color>

    An example:

        color 15 1

    This will result in white text on a blue background. These are the valid
    color codes:

         0 = Black
         1 = Blue
         2 = Green
         3 = Cyan
         4 = Red
         5 = Magenta
         6 = Brown
         7 = Light gray
         8 = Dark gray
         9 = Light blue
        10 = Light green
        11 = Light cyan
        12 = Light red
        13 = Light magenta
        14 = Yellow
        15 = White

    Note that you can only use the colors 0-7 for background colors. In
    order for the COLOR command to work, you must load ANSI.SYS or a
    compatible screen driver.

    Use the included utility COLORS to see how the different color codes
    look on your screen.


    DATESTR
    ───────

    Displays the current date on the screen. The format is:

        DATESTR <column> <line>

    The date is displayed in the format DD.MM.YY, and in the current color.


    DELAY
    ─────

    Pauses the execution of the program for the specified number of
    seconds. The format is:

        DELAY <seconds>

    This command, for example, will result in a 5-second pause:

        delay 5

    The parameter can be in the range 0 to 60 seconds.


    ECHO
    ────

    Displays a text string on the screen. Format:

        ECHO <text>

    The forms ECHO [ON | OFF] are not supported, as Batman never echoes any
    commands anyway.

    A blank line can be displayed by echoing just a period:

        echo .

    This is a common method for displaying blank lines, and is implemented
    is several DOS versions.


    FOR
    ───

    Constructs a loop which allows you to repeat a command for selected
    files. The format is:

        FOR <variable> IN (<file specification>) DO <command>

    An example:

        for %%x in (*.txt) do copy %%x lpt1:

    This command will print all files with the extension ".TXT" on the
    printer.


    GOTO / GOSUB / RETURN
    ─────────────────────

    These commands allow you to transfer control to another place in the
    batch file. Formats:

        GOTO <label>
        GOSUB <label>

    Such jumps can only be made to lines that contain a "label". This is a
    line which starts with a colon, for example:

        :label1

    Batman distinguishes only between the first 8 characters i label names.

    If the jump is made by means of the GOSUB command, you can return to
    the following line with the RETURN command. This is not the case when
    control is transferred with the GOTO command.

    GOSUB commands may be nested:

        :start
     ┌─ gosub label_1
     │  return        <─┐
     └> :label_1        │
     ┌─ gosub label_2   │
     │  echo Label 1  <┐│
     │  return        ─│┘
     └> :label_2       │
        echo Label 2   │
        return        ─┘

    You can nest GOSUB commands in 64 levels.


    IF
    ──

    Logical condition.  Format:

        IF [NOT] <condition> <command>

    where

        <condition> = <text>==<text>        or
                       EXIST <filename>     or
                       ERRORLEVEL <value>

    The <command> is executed if the condition is true. All forms are
    supported, included IF NOT, IF EXIST, IF NOT EXIST, IF ERRORLEVEL
    and IF NOT ERRORLEVEL.  An example:

        if %1==lpt1: echo Printing to %1


    INKEY
    ─────

    Stops the execution of the program and waits until the user presses a
    key. The response is stored in a variable (%%A - %%Z), and can
    optionally be converted into upper case. A prompt can also be
    displayed. Format:

        INKEY [<text>] <variable> [UPPER]

    A few examples:

        inkey %%s
        inkey Continue? %%s
        inkey "Type Y or N" %%s upper

    All three examples stop and wait for the user to press a key. Note
    that if the prompt contains blanks, it must be enclosed in double
    quotes for Batman to interpret it correctly. In the third example the
    response will automatically be converted into upper case before it is
    stored in the variable %%S.


    INPUT
    ─────

    Stops execution of the program and waits for the user to type a string
    of characters and press Return. The response is stored in a variable,
    and can optionally be converted to upper case. A prompt can also be
    displayed. Format:

        INPUT [<text>] <variable> [UPPER]

    Some examples:

        input %%x
        input Filename? %%x
        input "Enter your response: " %%x upper

    The user's response may be up to 127 characters in length. Note
    that if the prompt contains blanks, it must be enclosed in double
    quotes. In the last example, the string is converted into upper case.


    LOOP / ENDLOOP
    ──────────────

    These two commands let you execute a group of command a specified
    number of times. Valid formats are:

         LOOP <constant>
         LOOP <variable>

         ENDLOOP

    The first command in the loop is the LOOP command. This requires a
    parameter which specifies how many times the loop is to be executed.
    The loop ends with an ENDLOOP command. An example:

        loop 10
        echo Ten times
        endloop

    These commands will display the text "Ten times" on the screen ten
    times (clever, no?). Instead of specifying a constant value for the
    number of iterations, you can also use a variable. Here's an example:

        set %%a=10
        loop %%a
        echo Line %%a
        endloop

    These commands will display this on the screen:

        Line 1
        Line 2
           .
           .
           .
        Line 10

    Loops can be nested in up to 8 levels.


    MENU / ITEM / ENDMENU
    ─────────────────────

    Menus can be built automatically with Batman. A menu always starts with
    the MENU command, which looks like this:

        MENU <title> <column> <line>

    The parameters specify the menu's title, and the location of its upper
    left corner. One or more menu selections can then be built with the
    ITEM command:

        ITEM <text> <label>

    The parameter <text> is the text which is displayed in the menu, and
    <label> is the label to which control will be transferred when the user
    selects this menu item. See the GOTO command for more information on
    labels.

    The last line in a menu construct contains the ENDMENU command. Let's
    look at an example:

        :start
        menu " Main menu " 10 5
        item "1. WordPerfect" wp
        item "2. Exit" done
        endmenu
        :wp
        wp.exe
        goto start
        :done

    These commands will display the following menu on column 10, line 5:

        ┌ Menu ──────────┐
        │ 1. WordPerfect │
        │ 2. Exit        │
        │                │
        │ Select: _      │
        └────────────────┘

    The user can press "1" or "2" in order to jump to the associated
    labels.


    PATH
    ────

    Sets DOS' search path.  Format:

        PATH=<directory>[;<directory>]

    See your DOS manual for more information about the search path.


    PAUSE
    ─────

    Displays a message on the screen and waits for the user to press a key.
    The format is:

        PAUSE [<text>]

    If you don't specify a message, the standard message "Press any key..."
    will be displayed. You can prevent a message from being displayed in
    this way:

        pause >nul

    This redirects the standard message to the NUL: device.


    PROMPT
    ──────

    Sets the DOS prompt. Format:

        PROMPT <text>

    See you DOS manual for more information about the DOS prompt.


    QUIT
    ────

    Terminates the program. You can optionally specify a return code
    (errorlevel) in the range 0 to 255. Format:

        QUIT [<errorlevel>]

    If the program is called by a batch file or another Batman program,
    this return code can be read by the calling program through the
    variable ERRORLEVEL. An example:

        The file TEST.BAT:

        call test2
        if errorlevel 1 echo The user responded yes

        The file TEST2.BAT:

        inkey "Answer Yes or No: " %%s
        if %%s==N quit
        if %%s==Y quit 1

    The command QUIT without parameters is equivalent to QUIT 0.


    SET
    ───

    Sets DOS' environment variables. Format:

        SET <variable>=[<value>]

    Examples of such variables are PATH and COMSPEC. You can also set
    Batman's variables (%%A - %%Z) with this command.

    If no value is specified, the variable is reset. See the DOS manual for
    further information.


    SHIFT
    ─────

    Moves the program's parameters "to the left".  If, for instance, you
    have this batch file:

        :start
        if "%1"=="" goto done
        copy %1 lpt1:
        shift
        goto start
        :done

    and run it with the parameters FIL1 and FIL2, the parameter %1 will
    contains "FIL1" the first time the IF command is executed, and "FIL2"
    the second time.


    XY
    ──

    This command places the cursor on a specified position on the screen.
    The format is:

        XY <column> <line>

    An example:

        xy 5 10

    This moves the cursor to column 5, line 10. Only constants can be used
    for specifying cursor positions, not variables.



    VARIABLES
    ─────────

    When you run a program compiled with Batman, up to 9 parameters can be
    included in the command. These are stored in the variables %1 to %9. An
    example:

        prtfiles customer.dat product.dat

    This command starts the program PRTFILES.EXE, and sets the variables to
    these values:

        %1 = customer.dat
        %2 = product.dat

    If you are using DOS version 3.0 or higher, the variable %0 will
    contain the name of the running program; PRTFILES.EXE in this case.

    You can also use the internal variables %%A to %%Z. These are among
    other things useful in FOR commands. Please note that an environment
    variable by the same name is created whenever you use an internal
    variable. An example:

        input %%a

    If the user responds "Gotham", two things will happen: the variable %%A
    will be set to "Gotham", and an environment variable which looks like
    this will be created:

        A=Gotham

    Environment variables can be referenced by typing a percent sign before
    and after the variable name, for example:

        echo %path%

    Undefined variables return an empty string.



    EXTERNAL COMMANDS
    ─────────────────

    External commands are all other commands than those described in the
    preceding sections.

    This section contains a somewhat technical discussion, so here's a
    brief summary for those of you who prefer English to Latin.

    If you are experiencing problems with commands other than those
    described above, try one of these solutions:

    - Try compiling the program with the /C option. If still no luck:

    - Change all external commands (i.e. commands not described above) by
      inserting the environment variable COMSPEC plus the parameter /C at
      the beginning of the lines. As an example, let's look at a command
      for starting WordPerfect:

          wp

      This should be changed to:

          %comspec% /c wp.exe

      If you're still having problems:

    - Type SET and press Return at the DOS command line. You will see a
      list of the so-called environment variables on the screen. One of
      these is called COMSPEC. Write down what it says behind the equal
      sign (usually something like C:\DOS\COMMAND.COM). Then insert this
      plus the parameter /C at the beginning of all external commands in
      your batch file. Let's look at the WordPerfect example again:

          wp

      This should be changed to:

          c:\dos\command.com /c wp.exe

      This example assumes that the WordPerfect program is located in a
      directory which is included in the PATH variable. If this is not the
      case, add the name of your WordPerfect directory also. If your copy
      of WordPerfect is stored in the directory C:\WP, the command should
      look like this:

          c:\dos\command.com /c c:\wp\wp.exe

      Make sure that the original batch file works the way it should before
      you attempt to compile it.


    The remainder of this section is devoted to a more technical discussion
    on the use of external commands.

    There are two types of external commands in Batman: those who are
    separate programs like for instance WordPerfect and the DOS program
    FORMAT, and those that are internal DOS commands, like DIR and TYPE. If
    you find it confusing that internal DOS commands are external commands,
    this is simply because Batman has to ask DOS to execute them, which
    means that they are external to Batman.

    If you specify an external command in the .BAT-file, Batman will first
    check whether it's one of DOS' internal commands. If this is not the
    case, Batman (or, rather, the compiled program) will search for an
    executable file with the extension .COM or .EXE. The search is
    conducted in the current directory and in the directories listed in the
    PATH variable. If no file is found, the message "Unknown command" will
    be issued.

    Commands that are internal to DOS must be executed by DOS. These are:

        BREAK   CHCP    CHDIR   CD      COPY    CTTY
        DATE    DEL     DIR     ERASE   MKDIR   MD
        RENAME  REN     RMDIR   RD      TIME    TYPE
        VER     VERIFY  VOL

    Batman programs use two different ways of execute external commands.
    The safest, but slowest method is by loading a copy of COMMAND.COM and
    letting it execute the command. Normally, Batman programs will attempt
    to avoid this, and use a faster method instead. This method is reliable
    in most versions of DOS, but should you encounter problems with the
    execution of external commands, you can force Batman to use COMMAND.COM
    by compiling with the /C option.

    If external commands are executed by loading a secondary copy of
    COMMAND.COM, either because of it's automatically selected or because
    the program is compiled with the /C option, performance can be improved
    by creating a RAM disk and copying COMMAND.COM onto it. You must also
    remember to change the COMSPEC variable:

        COPY COMMAND.COM D:\
        SET COMSPEC=D:\COMMAND.COM

    This will lead to faster execution of all external commands.

    The utility EXCOM reports which method Batman will use, and where
    COMMAND.COM will be loaded from.

    Some programs require the use of COMMAND.COM; one example of this is
    the DOS program DISKCOPY. This problem can be solved by specifying
    COMSPEC or COMMAND.COM as part of the command:

        %comspec% /c diskcopy a: b:

    or:

        command /c diskcopy a: b:

    Note that the /C parameter must be included.

    Users of 4DOS and other similar systems should of course replace
    COMMAND.COM with the appropriate commands. An example of an 4DOS
    command that needs special treatment is LIST, which is not found in
    DOS:

        4dos /c list %1

    This command should also work if you use the COMSPEC variable, which
    may make your program more foolproof:

        %comspec% /c list %1

    Since loading a secondary copy of the command processor is slower and
    consumes more memory, you should use it only when necessary.



    CALLING OTHER BATCH FILES
    ─────────────────────────

    If you wish to run batch files that are not compiled, this must be done
    by DOS, i.e. you must use one of these methods:

        %comspec% /c <batch file>
        command /c <batch file>

    See also the previous section and the description of the CALL command.



    ERROR MESSAGES
    ──────────────

    There are a few limitations as to what batch files Batman can handle.
    You cannot have than 255 different labels; then you will receive this
    message:

        Too many labels

    and Batman will abort. Also, you cannot have more than 255 references
    to labels that further down than the GOTO or GOSUB commands. That will
    lead to this message:

        Too many references to undefined labels


    All labels that are referenced by GOTO or GOSUB commands must of course
    be defined somewhere in the file, or you will receive this message:

        Undefined label: <name>

    These limitations should not mean any difference.

    Compilation of very big batch files may result in this message:

        Too much code

    This means that the file is too big for Batman to process, but this is
    very unlikely. If you try to run Batman with too little memory
    available, you will see this message:

        Not enough memory

    If you specify invalid parameters for the XY command, you will get this
    message:

        Invalid XY parameter

    If you try to use invalid variable names in the INKEY command, Batman
    will issue this message:

        Invalid INKEY variable

    If the sequence of the MENU, ITEM and ENDMENU commands is wrong, you
    will see one of these messages:

        ITEM outside MENU
        ENDMENU without MENU
        Invalid command in MENU

    Invalid parameters for the COLOR command, i.e. foreground colors
    outside the range 0-15 or background colors outside the range 0-7 will
    result in this message:

        Invalid color code

    The LOOP command can use either a variable (%%A - %%Z) or a constant as
    argument. If you try to use something else, or if the variable or
    constant is non-numeric, this is how Batman will respond:

        Invalid LOOP variable

    More than 8 nested LOOP commands will result in this message:

        Too many LOOP levels

    If you have fewer ENDLOOPs that LOOPs, Batman will say to you:

        ENDLOOP without LOOP

    Batman only performs limited error checking, so don't try to compile a
    file until you know it's correct. Test it properly first.



    FINAL WORDS
    ───────────

    I hope you find Batman useful. Suggestions for improvements and bug
    reports are welcomed.



    APPENDIX A. LIST OF COMMANDS
    ────────────────────────────

        BELL
        CALL    <filename>
        CLOCK   OFF | ON <column> <line> <foreground color> <background color>
        CLREOL
        CLS
        COLOR   <foreground color> <background color>
        DATESTR <column> <line>
        DELAY   <seconds>
        ECHO    <text>
        ENDLOOP
        ENDMENU
        FOR     <variable> IN (<file specification>) DO <command>
        GOSUB   <label>
        GOTO    <label>
        IF      [NOT] <condition> | EXIST <filename> | ERRORLEVEL <command>
        INKEY   [<text>] <variable> [UPPER]
        INPUT   [<text>] <variable> [UPPER]
        ITEM    <text> <label>
        LOOP    <constant> | <variable>
        MENU    <title> <column> <line>
        PATH    <search path>
        PAUSE   [<text>]
        PROMPT  <text>
        QUIT    [<errorlevel>]
        RETURN
        SET     <environment variable>=<text>
        SHIFT
        XY      <column> <line>